• create a working Edit menu that automatically edits the active
field’s text
• create editing fields with different fonts
• create an editing field that is limited to a certain number
of characters
• respond to Tools Plus events pertaining to editing fields
• put text into a field under application control
• get text from a field under application control
When you create an editing field, Tools Plus executes thousands of lines of code to make it look and feel the way it should. You can easily create professional fields where other developers (without Tools Plus) settle for “good enough” and just use the basics of the Macintosh toolbox.
When using Editing Fields, take particular notice of these automatic features (you don’t have to do anything to get these features)…
• the cursor changes to an I-beam when entering an editing field
• the Edit menu automatically applies itself to the active field
• automatic undo/redo (preserving your character selection)
• text scrolling is a significant improvement over the toolbox’s
build-in scrolling (it “feels better” by scrolling faster as you
move your cursor further out of the field)
• cursor control keys work as you’d expect in editing fields
• the Shift key extends and shortens your selection when used
in conjunction with cursor keys
• the Option key, when used with cursor keys, moves you to the
beginning of the next/previous word (Option = move by word)
• the Shift key can be used in conjunction with the Option key to
extend/shorten your selection a word at a time.
Editing Menu
~~~~~~~~~~
To make the most of editing fields, your application should have an Edit menu with the first six items as follows:
1) Undo Cmd Z
2) ------------
3) Cut Cmd X
4) Copy Cmd C
5) Paste Cmd V
6) Clear
Tools Plus takes care of enabling and disabling the individual items based on the user’s activity in the active editing field.
The “Undo” item works as you would expect: undoing the user’s last change. The “Undo…” item’s text changes to indicate what will be undone, such as:
Undo Cut
Undo Copy
Undo Paste
Undo Typing
and so on. What may come as a pleasant surprise is that Undo _also_ works as a Redo… command. For example, when the user starts typing in a field, the Undo item is automatically renamed to “Undo Typing”. If the user uses the Edit menu’s “Undo Typing” item, the typing is undone and the menu changes to “Redo Typing” thereby letting the user undo the undoing. This also applies to the Cut, Copy, Paste and Clear operations.
You don’t have to worry about having enough memory to undo or redo, since this is all handled by Tools Plus.
How Fields Work
~~~~~~~~~~~~~
Each editing field needs to be “connected to” its text (supplied by your application when creating the field). Both your application and the editing field will access this text.
When your application activates a field, Tools Plus makes a _copy_ of the text you provided and lets the user edit the _copy_ (not the original text). When the user is finished editing the field (by tabbing or clicking to another field, etc), your application decides if the edited text should be discarded or saved (overwriting the original text). Here is an example:
When you are writing your application, _you_ decide when you want to edit a field’s text and when you want to save the edited text. As an alternative, you may want to perform all editing only if the user clicks the “OK” button instead of on a field-by-field basis. It’s completely up to you.
Before You Create an Editing Field
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Before you create an editing field, you’ll need to create an object that holds the field’s text. Tools Plus’ editing fields expect a handle that points to a Pascal string.
You can create this record yourself any way you want. Tools Plus includes the NewStrHandle routine that allocates space and initializes the string to “” (null string, length = 0). NewStrHandle is handy because it lets you allocate a string of a specific length and initialize it to null with one line of code.
Each editing field MUST have its own text handle. It’s okay if two fields share the same text handle providing the two fields do not exist at the same time.
Why a “handle” to a string?…
√ handles reduce memory fragmentation
√ Tools Plus uses less memory by making a copy of your text only
when needed. When inactive fields are refreshed by Tools Plus,
they display your text (by dereferencing your handle) without
having to keep a copy of the text hanging around.
√ Tools Plus can optionally resize the handle to be the size of the
text it contains, making T+ even more memory-efficient!
√ Tools Plus will soon work with large text fields up to 32K, which
are best referenced by handle to reduce memory fragmentation
Creating Editing Fields
~~~~~~~~~~~~~~~~~~
To create an editing field, you do the following:
(1) CurrentWindow… tell Tools Plus which window is the target
of subsequent actions (i.e., the current
window)
(2) NewField… create the new field
The “Editing Fields” chapter details the parameters required by the NewField or NewFieldRect routines.
Activating Editing Fields
~~~~~~~~~~~~~~~~~~~~
Your application can activate a field by using ActivateField. This typically happens when you create a window with new fields. You can also activate a field in response to the user’s action:
user Tabs or Shift/Tabs… ActivateField
user clicks in a field… ClickInField
The Event Loop
~~~~~~~~~~~~
The Tools Plus events you will likely need to handle are:
doKeyDown, doAutoKey Detect Tab and Shift/Tab
doClickField User clicked in an inactive field
A less commonly used event is doChgInField which tells you something occurred in the field that changed the text (it could be any typing, editing, undoing or redoing). Here’s an example of when the doChgInField event is useful:
- creating a “log on” window with a User Name and a Password
field (both fields are empty)
- create an enabled “Cancel” button, and a disabled “OK” button
- you want the “OK” button to be enabled only when both fields are
not empty
- each time you get a doChgInField event, do the following:
